/*-
 * Copyright (c) 2009 Jonathan Anderson
 * All rights reserved.
 *
 * WARNING: THIS IS EXPERIMENTAL SECURITY SOFTWARE THAT MUST NOT BE RELIED
 * ON IN PRODUCTION SYSTEMS.  IT WILL BREAK YOUR SOFTWARE IN NEW AND
 * UNEXPECTED WAYS.
 * 
 * This software was developed at the University of Cambridge Computer
 * Laboratory with support from a grant from Google, Inc. 
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifndef UA_FILE_H

#include <sys/capability.h>

#include <QString>

#include "Crypto.h"


//! Represents a file (name and/or descriptor) accessed by the User Angel
class File
{
	public:
	/**
	 * Constructor.
	 *
	 * @param   filename    the full path and filename ("" if not known)
	 * @param   fd          the raw file descriptor
	 * @param   rights      capability rights
	 */
	File(QString filename = "", int fd = -1, cap_rights_t rights = 0);
	File(const File&);
	~File();

	File& operator = (const File&);         //!< assignment operator
	bool operator == (const File&) const;   //!< equality test

	QString capName() const;                //!< capability string

	bool isValid() const;                   //!< is the capability valid?
	int fd() const;                         //!< the actual file descriptor
	cap_rights_t rights() const;            //!< assigned capability rights

	/**
	 * Upgrade this (read-only) capability to a read-write one.
	 * 
	 * If called on a read-write capability, another (refcounted) copy of the
	 * same capability is returned.
	 *
	 * If the file cannot be opened read-write (due to permissions issues or
	 * not having the underlying file's filename), a wrapper around the FD
	 * value -1 is returned (so isValid() will return false).
	 */
	File upgrade() const;

	void setName(QString);              //!< set the actual filename + path
	QString filename() const;           //!< get the actual filename + path
	QString safeName() const;           //!< only the file's name (no path)


	private:
	int* _refcount;               //!< how many of this File are open

	int _fd;                      //!< file descriptor
	cap_rights_t _rights;         //!< capability rights
	QString _name;                //!< full filename

	Crypto::Ciphertext _token;    //!< capability token
};


#define UA_FILE_H
#endif

